home *** CD-ROM | disk | FTP | other *** search
/ CICA 1993 April / CICA MS Windows - April 1993.iso / unzipped / programr / vbasic / hugary / hugearr.txt < prev    next >
Text File  |  1992-03-11  |  18KB  |  565 lines
  1.  
  2.                                 HUGEARR.DLL
  3.                Huge array support for Microsoft Visual Basic
  4.  
  5.               from Microsoft Product Support Services 6/4/91
  6.               with additions by various authors
  7.  
  8. The following information applies to Microsoft Visual Basic
  9. programming system version 1.0 for Microsoft Windows, and to Microsoft
  10. Windows 3.0 Software Development Kit (SDK).
  11.  
  12. HUGEARR.DLL is a dynamic-link library (DLL) which contains functions
  13. for creation, maintenance, and deletion of arrays larger than 64K from
  14. Microsoft Visual Basic version 1.00 for Windows. This DLL also gives
  15. the ability to create arrays with more than 32,767 (32K) elements per
  16. dimension, and to redimension arrays while preserving the data inside
  17. of the arrays.
  18.  
  19. The following files are provided:
  20.  
  21.    HUGEARR.DLL, HUGEARR.BAS, HUGEARR.C, HUGEARR.DEF, HUGEARR.H,
  22.    HUGEARR.TXT, MAKEFILE
  23.  
  24. To use the functions in HUGEARR.DLL, simply copy the declarations
  25. contained in HUGEARR.BAS into your global module in Visual Basic and
  26. copy HUGEARR.DLL to your Windows directory. The functions can then be
  27. used like any other Windows DLL function.
  28.  
  29. HUGEARR.DLL allocates memory using the Windows API function
  30. GlobalAlloc. This means that the largest array that can be allocated
  31. is 1 MB in standard mode, and 64 MB in 386 enhanced mode for Windows.
  32.  
  33. The following routines are contained in HUGEARR.DLL. For a complete
  34. description of the parameters and/or return values of these routines,
  35. see Visual Basic's Declare statement for the routine in question in
  36. the file HUGEARR.BAS.
  37.  
  38. HUGEARR.DLL Language Reference:
  39. ------------------------------
  40.  
  41. -------------------------------------------------------------------------
  42. HugeDim:
  43.  
  44. Action: Dimensions an array and returns a handle to that array.
  45.  
  46. Syntax: HugeDim(recsize%, limit&)
  47.  
  48. Argument       Description
  49. --------       -----------
  50.  
  51. recsize%       The size of each element in the array.  (i.e. an integer
  52.                would be 2, a double would be 8.)  You can use the Len()
  53.                function to determine the size of any data type if you are
  54.                unsure.
  55.  
  56. limit&         The upper bound of the array.  The lower bound of all arrays
  57.                is 0, so for example: 'HugeDim(2, 10)' would create an
  58.                integer array of elements 0 through 10.
  59.  
  60. Remarks:
  61. -------
  62.  
  63. You should not try to create a huge array of variable-length strings, or of
  64. a user-defined type that contains variable-length strings.  Visual Basic's
  65. string handling routines would not know of the existence of any string that
  66. was controlled by HUGEARR.DLL, and a UAE ("Unrecoverable Application Error")
  67. would probably result.  Fixed-length strings are okay though.
  68.  
  69. HugeDim returns a handle to the array that was created, and that handle is
  70. used when referring to that array with other commands.  If an error
  71. occurred (such as out of memory), it will return a negative number.  Error
  72. codes are detailed below under the section entitled 'Error Codes'.
  73.  
  74. Example:
  75. -------
  76.  
  77. Sub Command1_Click()
  78.      Dim hArray as integer
  79.      Dim variable as SomeUserDefinedType
  80.  
  81.      hArray = HugeDim(Len(variable), 10)
  82.      If hArray < 0 Then
  83.           print "Error dimensioning array:"; hArray
  84.           Stop
  85.      End If
  86.           .
  87.           .
  88.           .
  89.      i% = HugeErase(hArray)
  90. End Sub
  91.  
  92. -------------------------------------------------------------------------
  93. HugeErase:
  94.  
  95. Action: Erases an array that was previously dimensioned using HugeDim.
  96.  
  97. Syntax: HugeErase(hArray%)
  98.  
  99. Argument       Description
  100. --------       -----------
  101.  
  102. hArray%        The handle to the array.  (The same handle that was returned
  103.                by HugeDim.)
  104.  
  105. Remarks:
  106. --------
  107.  
  108. You should be sure to HugeErase all arrays that were HugeDim'd.  Failing to
  109. do so would cause the memory used by the array to not be freed up until the
  110. application quits.  If many arrays are dimensioned but never erased memory
  111. would keep being allocated without being freed, eventually degrading system
  112. performance.
  113.  
  114. Example:  Refer to the example for HugeDim.
  115.  
  116. -------------------------------------------------------------------------
  117. HugeRedim:
  118.  
  119. Action:  Redimensions an array created with HugeDim to a different size.
  120.  
  121. Syntax:  HugeRedim(hArray%, limit&)
  122.  
  123. Argument       Description
  124. --------       -----------
  125.  
  126. hArray%        The handle to the array to redimension.
  127.  
  128. limit&         The new upper bound of the array.
  129.  
  130. Remarks:
  131. --------
  132.  
  133. HugeRedim, unlike Visual Basic's ReDim, preserves all the data in the
  134. array.  If you want to erase the contents of the array, you should erase it
  135. and the dimension it again.
  136.  
  137. If the size of the array would go over 64K when it is redimensioned, it is
  138. subject to the same size restrictions detailed in the discussion of
  139. HugeDim.
  140.  
  141. You cannot change the size of the elements in the array, only the number of
  142. elements.
  143.  
  144. Example:
  145. --------
  146.  
  147. Sub Command1_Click()
  148.      .
  149.      .
  150.      i% = HugeRedim(hArray, 50)
  151.      if i% < 0 then
  152.           print "error redimensioning array:"; hArray
  153.           stop
  154.      End If
  155.  
  156.      e% = HugeErase(hArray)
  157. End Sub
  158.  
  159. -------------------------------------------------------------------------
  160. GetHugeEl, SetHugeEl:
  161.  
  162. Action:  Gets or sets the contents of an array element.
  163.  
  164. Syntax:  GetHugeEl(hArray%, el&, variable)
  165.         SetHugeEl(hArray%, el&, variable)
  166.  
  167. Argument       Description
  168. --------       -----------
  169.  
  170. hArray%        The handle to the array.
  171.  
  172. el&            The element of the array to set or get the data from.
  173.  
  174. variable       The variable to get into, or to set the array from.
  175.  
  176. Remarks:
  177. --------
  178.  
  179. It is extremely important that the type for the variable passed to
  180. GetHugeEl or SetHugeEl matches that type of the variable used in the
  181. HugeDim statement, if the types are of different lengths, you will mostly
  182. likely get a UAE or overwrite other data.  If you want to be sure that the
  183. types match you can use the Alias keyword when you declare the function to
  184. introduce type checking.  Refer to the section below entitled 'Aliasing'
  185. for more information on aliases.
  186.  
  187. Example:
  188. --------
  189. Sub Command2_Click()
  190.      .
  191.      .
  192.      .
  193.      hArray = HugeDim(len(i%), 10)
  194.      If hArray < 0 Then Stop
  195.      e% = SetHugeEl(hArray, 1, 54%)               ' puts 54 into element #1
  196.      If e% < 0 Then Stop                ' check error code
  197.      e% = GetHugeEl(hArray, 1, i%)           ' get element #1 into i%
  198.      Print i%
  199.  
  200.      e% = HugeErase(hArray)
  201. End Sub
  202.  
  203. -------------------------------------------------------------------------
  204. GetHugeNEl, SetHugeNEl:
  205.  
  206. Action:  Gets or sets the contents of multiple array elements.
  207.  
  208. Syntax:  GetHugeNEl(hArray%, el&, nelem%, variable)
  209.          SetHugeNEl(hArray%, el&, nelem%, variable)
  210.  
  211. Argument       Description
  212. --------       -----------
  213.  
  214. hArray%        The handle to the array.
  215.  
  216. el&            The first element of the array to set or get the data from.
  217.  
  218. nelem%         The number of elements to be set or fetched.
  219.  
  220. variable       The variable to get into, or to set the array from.
  221.  
  222. Remarks:
  223. --------
  224. See the Remarks for GetHugeEl, SetHugeEl.
  225.  
  226. Example:
  227. --------
  228. Sub Command2_Click()
  229.      .
  230.      .
  231.      Dim VBArray() as Double
  232.      ReDim VBArray(1 to 1000)
  233.      ' Assign something to the elements in VBArray.
  234.      .
  235.      .
  236.  
  237.      hArray = HugeDim(len(i#), 1000)
  238.      If hArray < 0 Then Stop
  239.  
  240.      ' Copy 1000 elements from VB array VBArray(1...1000) to huge array.
  241.      e% = SetHugeNEl(hArray, 1, 1000, VBArray(1))
  242.      ' check error code
  243.      If e% < 0 Then Stop
  244.  
  245.      ' Copy 1000 elements from huge array to VB array VBArray(1...1000).
  246.      e% = GetHugeNEl(hArray, 1, 1000, VBArray(1))
  247.  
  248.      e% = HugeErase(hArray)
  249. End Sub
  250.  
  251. ------------------------------------------------------------------------
  252. HugeSave:
  253.  
  254. Action:  Saves the specified number of elements of a huge array to the
  255.          named file.
  256.  
  257. Syntax:  HugeSave(hArray%, NEl&, RecLen%, Fn$)
  258.  
  259. Remarks:
  260. -------
  261.  
  262. The number of elements to save as well as the size of each element,
  263. together with the full filename of the file to be written to must be
  264. spupplied.
  265.  
  266. Example:
  267. --------
  268.  
  269. Sub Command6_Click()
  270.  
  271.        ErrCode& = HugeSave(hArray, hArrayElements&, hArryRecLen%, "MYFILE.ARR")
  272.        If ErrCode& < 0 Then Stop
  273.  
  274. End Sub
  275.  
  276. ---------------------------------------------------------------------------
  277. HugeLoad:
  278.  
  279. Action:  Loads a huge array from the named file.
  280.  
  281. Syntax:  HugeLoad(hArray%, RecLen%, Fn$)
  282.  
  283. Remarks:
  284. -------
  285.  
  286. The file is read until EOF is found.  The number of element read are
  287. returned unless an error occurs.  The Array to be loaded must be
  288. allocated sufficient space to hold the array before this function is
  289. called.
  290.  
  291. Example:
  292. --------
  293.  
  294. Sub Command7_Click()
  295.  
  296.        Open "MYFILE.ARR" For Random As #1 Len = hArrayRecLen%
  297.        hArrayElements& = LOF(1) / hArrayRecLen%
  298.        Close #1
  299.        hArray = HugeDim(hArrayRecLen%, hArrayElements&)
  300.        If hMain > 0 Then
  301.          hArrayElements& = HugeLoad(hArray, hArrayRecLen%, "MYFILE.ARR")
  302.          If hArrayElements& < 0& Then Stop
  303.        Else
  304.          Stop
  305.        End If
  306.  
  307. End Sub
  308.  
  309. -----------------------------------------------------------------------
  310. HugeInt:
  311. HugeLong:
  312. HugeSingle:
  313. HugeDouble:
  314. HugeCurrency:
  315.  
  316. Action:  Retrieves an element from an array of a given type.
  317.  
  318. Syntax:  HugeInt(hArray%, el&)
  319.          HugeLong(hArray%, el&)
  320.          HugeSingle(hArray%, el&)
  321.          HugeDouble(hArray%, el&)
  322.          HugeCurrency(hArray%, el&)
  323.  
  324. Argument       Description
  325. --------       -----------
  326.  
  327. hArray%        The handle to the array.
  328.  
  329. el&            The element to retrieve.
  330.  
  331. Remarks:
  332. --------
  333.  
  334. This family of functions is provided as a shortcut alternative to GetHugeEl
  335. to retrieve a given data type while in an expression.  For example:
  336.  
  337.      value = HugeDouble(hArray, 0) * HugeDouble(hArray, 1)
  338.  
  339. The example above could have been done using GetHugeEl; however, the values
  340. returned by the two HugeDouble calls would have to be assigned to
  341. variables, and then the variables would be used in the expression.  The
  342. example below expands more on this.
  343.  
  344. IMPORTANT: None of these functions return error codes, so you should use
  345. them only if you are positive that the value of hArray% and el& are legal
  346. values.  If a error does occur (such as a "Subscript Out of Range"), you
  347. will get meaningless results.  You should use GetHugeEl if you need to be
  348. able to check error codes.
  349.  
  350. Example:
  351. --------
  352.  
  353. Sub Command3_Click()
  354.      Dim hArray As Integer
  355.  
  356.      hArray = HugeDim(len(i%), 10)
  357.      If hArray < 0 Then Stop
  358.  
  359.      e% = SetHugeEl(hArray, 0, 3%)           ' Put 3 in element #0
  360.      If e% < 0 Then Stop                     ' Check for errors
  361.      e% = SetHugeEl(hArray, 1, 4%)           ' Put 4 in element #1
  362.      If e% < 0 Then Stop
  363.  
  364.      e% = GetHugeEl(hArray, 0, i%)           ' Get value of element #0
  365.      If e% < 0 Then Stop
  366.      e% = GetHugeEl(hArray, 1, j%)           ' Get value of element #1
  367.      If e% < 0 Then Stop
  368.      Print Sqr(i% ^ 2 + j ^ 2)
  369.  
  370.                                              ' Alternate (and faster)
  371.                                              ' way of doing the above.
  372.      Print Sqr(HugeInt(hArray, 0) ^ 2 + HugeInt(hArray, 1) ^ 2)
  373.  
  374.      e% = HugeErase(hArray)
  375. End Sub
  376.  
  377. -------------------------------------------------------------------------
  378. HugeUbound:
  379.  
  380. Action:  Returns the upper bound of a give array.
  381.  
  382. Syntax:  HugeUbound(hArray%)
  383.  
  384. Argument       Description
  385. --------       -----------
  386.  
  387. hArray%        The handle to the array.
  388.  
  389. Remarks:
  390. --------
  391.  
  392. This function is the same as Basic's 'Ubound' function.  It is used to
  393. return the current upper bound of an array.
  394.  
  395. If HugeUbound returns an negative value, it represents an error code.
  396.  
  397. Example:
  398. --------
  399.  
  400. Sub Command4_Click()
  401.      Dim hArray as integer
  402.  
  403.      hArray = HugeDim(len(i%), 23)
  404.      If hArray < 0 Then Stop
  405.  
  406.      for J& = 0 to HugeUbound(hArray)           ' Initialize array to 10's
  407.           ErrCode% = SetHugeEl(hArray, J&, 10%)
  408.           If ErrCode% < 0 Then Stop
  409.      Next J&
  410.      .
  411.      .
  412.      .
  413. End Sub
  414.  
  415. ------------------------------------------------------------------------
  416. NumHugeArrays:
  417.  
  418. Action:  Returns the number of free huge arrays available.
  419.  
  420. Syntax:  NumHugeArrays
  421.  
  422. Remarks:
  423. -------
  424.  
  425. This command is included mostly for debugging purposes.  It is used to find
  426. out how many array could be dimensioned at that time by the program.
  427.  
  428. Example:
  429. --------
  430.  
  431. Sub Command5_Click()
  432.  
  433.      Debug.Print NumHugeArrays
  434.  
  435. End Sub
  436.  
  437. ---------------------------------------------------------------------------
  438. Error Codes:
  439.  
  440. The following functions return error codes as described below:
  441.  
  442.      HugeDim, HugeErase, HugeRedim, GetHugeEl, SetHugeEl, HugeUbound,
  443.      HugeSave, HugeLoad
  444.  
  445. The possible error codes are:
  446.  
  447.      0    The function was successful.
  448.  
  449.      -1   "Out of Memory"  There is not enough global memory for the
  450.           HugeDim or HugeRedim
  451.  
  452.      -2   "To Many Arrays"  There are no free arrays left to be
  453.           dimensioned.
  454.  
  455.      -3   "Bad Element Size"  This error condition is no longer possible.
  456.  
  457.      -4   "Subscript out of Range"  The array element you are trying to
  458.           access is outside the bounds of the array.
  459.  
  460.      -5   "Illegal Array Handle"  The array that was referenced is not a
  461.           valid array.  Either it is not dimensioned, or the handle value
  462.           is illegal.
  463.  
  464.      -7   "Error Opening File"  The file specified could not be opened.
  465.  
  466.      -8   "Error Writing to File"  An error occurred during a file write
  467.           operation
  468.  
  469.      -9   "Error Reading File"  An error occurred during a file read
  470.           operation
  471.  
  472. ------------------------------------------------------------------------
  473. Aliasing:
  474.  
  475. The GetHugeEl and SetHugeEl functions transfer data back and forth from an
  476. array. Because these functions must work with any data type, they are
  477. declared 'As Any' in their declarations.  This has the disadvantage that it
  478. defeats Basic's built-in type checking, and allows the posibility of
  479. passing the wrong data type.
  480.  
  481. To work around this potential problem, you can use Basic's 'Alias' keyword
  482. in the declaration.  For example, if you wanted GetHugeEl to work with the
  483. data type 'UserType', you might rename the function to 'GetUserType', and
  484. alias it to 'GetHugeEl'.
  485.  
  486. The declaration for GetHugeEl contained in "HUGEARR.BAS"  is:
  487.  
  488.      Declare Function GetHugeEl Lib "hugearr.dll" (ByVal Index%,
  489.      ByVal el&, buffer As Any) As Integer
  490.  
  491. To force Basic to do type checking on the call, you would rewrite the
  492. declaration to be:
  493.  
  494.      Declare Function GetUserType Lib "hugearr.dll" Alias "GetHugeEl"
  495.      (ByVal Index%, ByVal el&, buffer As UserType) As Integer
  496.  
  497. Note that the 'buffer As Any' has been changed to 'buffer As UserType'.
  498. Because the function no longer has the 'As Any' type Basic will be able to
  499. raise an error if you try to pass the wrong data type.
  500.  
  501. A function can be aliased any number of times, so you may want to create an
  502. alias for each data type that you are using.
  503.  
  504. -----------------------------------------------------------------------
  505. Constants:
  506.  
  507. The SetHugeEl routine is used to assign values to an array.  For example,
  508. the following statement
  509.  
  510.      i% = SetHugeEl(hArray, 1, v%)
  511.  
  512. would assign the value stored in v% to element #1 of the array hArray.
  513. However, a problem can arise when you try to use a constant in place of the
  514. 'v%' above.  For example:
  515.  
  516.      i% = SetHugeEl(hArray, 1, 15)
  517.  
  518. In this case, Visual Basic would assume that the number 15 is an integer
  519. constant and would pass a pointer to an integer to the SetHugeEl routine;
  520. even if hArray is a (for instance) array of double-precision numbers.
  521. To work around this potential problem, you should always use a type suffix
  522. when passing constants to SetHugeEl.  If you wanted to assign the value
  523. of 15 to a double precision array, you would use the statement:
  524.  
  525.      i% = SetHugeEl(hArray, 1, 15#)
  526.  
  527. --------------------------------------------------------------------------
  528.  
  529. HUGEARR.DLL Memory and Capacity:
  530.  
  531. HUGEARR.DLL allocates memory using the Windows API function GlobalAlloc.
  532. This means that the largest array that can be allocated is 1 MB in standard
  533. mode, and 64 MB in 386 enhanced mode.
  534.  
  535. If you forget to HugeErase an array that was allocated with HugeDim,
  536. Windows will automatically deallocate the memory after your application
  537. terminates.  However, HUGEARR.DLL keeps the information it needs to
  538. maintain the arrays in it's own private area.  This means that any array
  539. which is not HugeErase'd will not have it's information released, and the
  540. array will not be marked as free.  If two applications are both using the
  541. DLL, and the first application HugeDim's all of the arrays and then quits
  542. without HugeEraseing them, the second application will not be able to
  543. create any arrays.
  544.  
  545. --------------------------------------------------------------------------
  546.  
  547. References:
  548.  
  549. HUGEARR.DLL is written in Microsoft C, and the C source code is
  550. provided with this application note in HUGEARR.C and HUGEARR.H.
  551. Advanced programmers can optionally modify and rebuild HUGEARR.DLL, by
  552. using Microsoft C Compiler version 6.00 or 6.00a and DLL libraries
  553. from the Microsoft Windows 3.0 Software Development Kit (SDK), and by
  554. running NMAKE.EXE with the enclosed MAKEFILE.  The MAKEFILE tells
  555. LINK.EXE to use the enclosed linker definition file, HUGEARR.DEF.
  556.  
  557. The following references discuss how to program Windows 3.0 DLL
  558. routines:
  559.  
  560. 1. "Programming Windows: the Microsoft Guide to Writing Applications
  561.    for Windows 3," by Charles Petzold (published by Microsoft Press,
  562.    1990)
  563.  
  564. 2. Microsoft Windows 3.0 Software Development Kit
  565.